<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Debugging: The Error Handler -->

<div class='chapter'>4. The Error Handler</div>
	The Lisp Machine Error Handler is an interactive subsystem which
can be used to examine and alter the state of the Lisp environment, and
to aid in debugging.  This chapter explains how to enter the error handler,
and how to use it.

<div class='section'>4.1 Entering the Error Handler</div>
	When an error is detected, the error handler is entered.
There are two kinds of errors:
those detected by the Lisp Machine's microcode, and those caused by Lisp
functions which have called a function such as <font class="lisp">ferror</font> or <font class="lisp">error</font>.  When there
is a microcode error, the error handler prints out a message such as the following:
<pre class="lisp">
&gt;&gt;TRAP 5543 (TRANS-TRAP)
The symbol FOOBAR is unbound.
While in the function *EVAL  SI:LISP-TOP-LEVEL1
</pre>
	The first line of this error message simply indicates entry to
the error handler; the mysterious numbers and so on are internal
information which may be useful for the maintainers of the error system
in case there are bugs in it.  The second line contains a description
of the error in English.  The third line indicates where the error
happened by printing a very abbreviated "backtrace" of the stack (see
below); in the example, it is saying that the error was taken by the
function <font class="lisp">*eval</font>, which was called by <font class="lisp">si:lisp-top-level1</font>.

	Here is an example of a macrocode error.

<pre class="lisp">
&gt;&gt;ERROR: The argument X was 1, which is not a symbol,
While in the function { FERROR  } FOO  *EVAL
</pre>
	Here the first line contains the English description of the
error message, and the second line contains the abbreviated backtrace.
The backtrace here indicates that the function which actually entered
the error handler was <font class="lisp">ferror</font>, but that function is indicated in
braces because it is not very important; the useful information here is
that the function <font class="lisp">foo</font> is what called <font class="lisp">ferror</font> and thus generated
the error.

There is not any good way to manually get into the error handler;
I think when we have interrupts
and so on we will need something to let you interrupt the machine and
examine the stack and so on.


	If you are writing a program which has detected an erroneous condition,
and wish to signal the error, one of the following two functions can be used.

<div class='defun'><font class='exdent'><font class='funcname'>ferror <font class='italic' color='purple'>code format-control-string &rest args</font></font></font><br>
	<font class="lisp">ferror</font> signals an error, causing the error handler to be
entered.  The error message printed is based on the arguments:
<font class="italic">format-control-string</font> should be a control string to be
given to the function <font class="lisp">format</font> (q.v.), and <font class="italic">args</font> are the 
rest of the arguments for <font class="lisp">format</font>.

	<font class="italic">code</font> is used to give the error system some idea of how to
treat the error in various ways.  For example, it can tell the error
system how to continue from the error.  Currently it is not
implemented, and all callers of <font class="lisp">ferror</font> should pass <font class="lisp">nil</font> as the
<font class="italic">code</font> argument. 

Example:
<pre class="lisp">
(ferror nil "The symbol ~S is not EQ to ~S" 'x 'y)
</pre>
from inside the function FOO which was called by
the function BAR would produce the error message
<pre class="lisp">
&gt;&gt;ERROR: The symbol X is not EQ to Y,
While in the function { FERROR  } FOO  BAR
</pre>
</div>

Note: the following function is provided primarily for Maclisp compatibility.
New programs should use the <font class="lisp">ferror</font> function as it is capable of producing
better formatted and more readable messages.

<div class='defun'><font class='exdent'><font class='funcname'>error <font class='italic' color='purple'>message object &optional code</font></font></font><br>
	<font class="lisp">error</font> signals an error, causing the error handler to be
entered.  The error message printed is <font class="italic">object</font> followed by <font class="italic">message</font>,
as in Maclisp.  The <font class="italic">code</font> argument is interpreted the same way as
in <font class="lisp">ferror</font>.

Example:
<pre class="lisp">
(error "The symbols are not EQ" (list 'x 'y))
</pre>
from inside the function FOO which was called by the function BAR
would produce the error message
<pre class="lisp">
&gt;&gt;ERROR: (X Y) The symbols are not EQ
While in the function { ERROR  } FOO  BAR
</pre>
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='check-args'>check-args</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">check-args</font> is a macro designed to make it convenient to check
the arguments of a function to see if they are reasonable.  A <font class="lisp">check-args</font>
form looks like this:
<pre class="lisp">
(check-args <font class="italic">var</font> <font class="italic">predicate</font> <font class="italic">message</font>)
</pre>
<font class="italic">var</font> is the name of the variable you want to check.  <font class="italic">predicate</font> is
used to determine whether the value of <font class="italic">var</font> is O.K. or not.  <font class="italic">predicate</font>
may either be the name of a predicate (.e.g <font class="lisp">symbolp</font>) of one argument, which
will be applied to the value of <font class="italic">var</font>, or if non-atomic it is an arbitrary form
which will be evaluated.  If <font class="italic">predicate</font> returns <font class="lisp">t</font>, then <font class="italic">var</font> is
O.K.; otherwise, an error is signalled.  <font class="italic">message</font> should be a string which
describes what the value of <font class="italic">var</font> should be.  For example, if some argument
<font class="lisp">a</font> of a function must be an array, and some other argument <font class="lisp">b</font> must
be a fixnum between 1 and 6 inclusive, one could write:
<pre class="lisp">
(check-arg a arrayp "an array")
(check-arg b (and (fixp b) (&gt;= b 1) (&lt;= b 6)) 
           "a fixnum between 1 and 6 inclusive")
</pre>
<!-- Need an example of the error message generated. -->
<!-- Right now the ^C command does not know how to continue.  This should be fixed. -->
</div>

<div class='section'>4.2 How to use the Error Handler.</div>
	Once inside the error hander, the user may give a wide variety
of commands.  This section describes how to give the commands, and then
explains them in approximate order of usefulness.  A summary is provided
at the end of the listing.

	When the error hander is waiting for a command, it prompts
with an arrow:

<pre class="lisp">

</pre>

	At this point, you may either type in a Lisp expression, or
type a command.  If you type a Lisp expression, it will be interpreted
as a Lisp form, and will be evaluated in the context of the function
which got the error.  (That is, all bindings which were in effect at
the time of the error will be in effect when your form is evaluated.)
The result of the evaluation will be printed, and the error handler
will prompt again with an arrow.  If, during the typeing of the form,
you change your mind and want to get back to the error handler's
command level,  type a Control-G; the error handler will respond with
an arrow prompt.  In fact, at any time that typein is expected from
you, you may type a Control-G to flush what you are doing and get back
to command level.  This <font class="lisp">read-eval-print</font> loop maintains the values
of <font class="lisp">+</font>, <font class="lisp">*</font>, and <font class="lisp">-</font> just as the top-level one does.

	Various error handler commands ask for Lisp objects, such as an
object to return, or the name of a catch-tag.  Whenever it tries to get
a Lisp object from you, it expects you to type in a <font class="italic">form</font>; it will
evaluate what you type in.  This provides greater generality, since
there are objects to which you might want to refer which cannot by
typed in (such as arrays).  If the form you type is non-trivial (not
just a constant form), the error handler will show you the result of
the evaluation, and ask you if it is what you intended.  It expects a Y
or N answer (see the function <font class="lisp">y-or-n-p</font>), and if you answer negatively
it will ask you for another form.  To quit out of the command, just type
Control-G.

<div class='section'>4.3 Error Handler Commands</div>
	All error handler commands are single characters, usually with the
Control or Meta bits.  The single most useful command is Control-Z, which
exits from the error handler and throws back to the Lisp top level loop.
ITS users should note that Control-Z is not Call.
Often you are not interested in using the error handler at all and just
want to get back to Lisp top level; so you can do this in one character.
This is similar to Control-G in Maclisp.

	Self-documentation is provided by the Help or "?" command,
which types out some documentation on the error handler commands.

	Often you want to try to continue from the error.  To do this,
use the Control-C command.  The exact way Control-C works depends on
the kind of error that happened.  For some errors, there is no standard
way to continue at all, and Control-C will just tell you this and
return to command level.  For the very common "unbound symbol" error,
it will get a Lisp object from you, which it will store back into the
symbol.  Then it will continue as if the symbol had been bound to
that object in the first place.  For unbound-variable or undefined-function
errors, you can just type Lisp forms to set the variable or define
the function, and then type Control-C; it will proceed without asking
anything.

	Several command are provided to allow you to examine the
Lisp control stack (regular pdl), which keeps a record of all functions which are currently
active.  If you call <font class="lisp">foo</font> at Lisp's top level, and it calls <font class="lisp">bar</font>,
which in turn calls <font class="lisp">baz</font>, and <font class="lisp">baz</font> gets an error, then a
backtrace (a backwards trace of the stack) would show all of this
information.  The error handler has two backtrace commands.  Control-B
simply prints out the names of the functions on the stack; in the above
example it would print
<pre class="lisp">
BAZ  BAR  FOO  *EVAL  LISP-TOP-LEVEL1  LISP-TOP-LEVEL
</pre>
The arrows indicate the direction of calling.  The Meta-B command prints
a more extensive backtrace, indicating the names of the arguments to the functions
and their current values, and also the saved address at which the function was
executing (in case you want to look at the code generated by the compiler);
for the example above it might look like:
<pre class="lisp">
FOO: (P.C. = 23)
   Arg 0 (X): 13
   Arg 1 (Y): 1

BAR: (P.C. = 120)
   Arg 0 (ADDEND): 13
</pre>
and so on.  This means that FOO was executing at instruction 23, and was called
with two arguments, whose names (in the Lisp source code) are X and Y.
The current values of X and Y are 13 and 1 respectively.

	The error handler knows about a "current stack frame", and there
are several commands which use it.  The initially "current" stack frame
is the one which signalled the error; either the one which got the microcode
error, or the one which called <font class="lisp">ferror</font> or <font class="lisp">error</font>.

	The command Control-L (or Form) clears the screen, retypes the
error message that was initially printed when the error handler was
entered, and then prints out a description of the current frame, in the
format used by Meta-B.  The Control-N command moves to the "next" frame
(that is, it changes the current frame to be the frame which is the one
following the current frame, moving towards the base of the stack), and prints
out the frame in this same format.  Control-P moves to the "previous" frame,
and prints out the frame in the same format.  Meta-&lt; moves to the
top of the stack, and Meta-&gt; to the bottom; both print out the new current
frame.

	Meta-L prints out the current frame in "full screen" format, which
shows the arguments and their values, the local variables and their values,
and the machine code with an arrow pointing to the next instruction
to be executed.
Meta-N moves to the next frame and prints
it out in full-screen format, and Meta-P moves to the previous frame and
prints it out in full-screen format.

	Control-A prints out the argument list for the function of the
current frame, as would be returned by the function <font class="lisp">arglist</font> (q.v.).
Control-R is used to return a value from the current frame; the frame
that called that frame continues running as if the function of the current frame
had returned.  This command prompts you for a form, which it will evaluate;
it returns the resulting value, possibly after confirming it with you.
Meta-R is used to return multiple values from the current frame, but
it is not currently implemented.  The Control-T command does a <font class="italic">throw</font>
to a given tag with a given value; you are prompted for the tag and the value.

	Control-Meta-A takes a numeric argument <font class="italic">n</font>, and prints out
the value of the <font class="italic">n</font>th argument of the current frame.  It leaves <font class="lisp">*</font>
set to the value of the argument, so that you can use the Lisp <font class="lisp">read-eval-print</font>
loop to examine it.  It also leaves <font class="lisp">+</font> bound to a locative pointing to the
<font class="italic">n</font>th argument on the stack, so that you can change that argument (by calling
<font class="lisp">rplaca</font> or <font class="lisp">rplacd</font> on the locative).  Control-Meta-L is similar,
but refers to the <font class="italic">n</font>th local variable of the frame.

<div class='section'>4.4 Summary of Commands:</div>
.table
.item Control-A
Print argument list of function in current frame.
.item Control-Meta-A
Examine or change the <font class="italic">n</font>th argument of the current frame.
.item Control-B
Print brief backtrace.
.item Meta-B
Print longer backtrace.
.item Control-C
Attempt to continue.
.item Control-G
Quit to command level.
.item Control-L
Redisplay error message and current frame.
.item Meta-L
Full-screen typeout of current frame.
.item Control-N
Move to next frame.  With argument, move down <font class="italic">n</font> frames.
.item Meta-N
Move to next frame with full-screen typeout.  With argument, move down <font class="italic">n</font> frames.
.item Control-P
Move to previous frame.  With argument, move up <font class="italic">n</font> frames.
.item Meta-P
Move to previous frame with full-screen typeout.  With argument, move up <font class="italic">n</font> frames.
.item Control-R
Return a value from the current frame.
.item Meta-R
Return several values from the current frame.
.item Control-T
Throw a value to a tag.
.item Control-Z
Throw back to Lisp top level.
.item ? or Help
Print a help message.
.item Meta-&lt;
Go to top of stack.
.item Meta-&gt;
Go to bottom of stack.
.end_table

<div class='section'>4.5 Miscellany</div>
	Sometimes, e.g. when the error handler is running,
microcode trapping is "disabled": any attempt by the
microcode to trap will cause the machine to halt.

<div class='defun'><font class='exdent'><font class='funcname'>trapping-enabled-p
This <font class='italic' color='purple'>predicate returns <font class="lisp">t</font> if trapping is enabled; otherwise</font></font></font><br>
it returns <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>enable-trapping <font class='italic' color='purple'>&optional (arg 1)</font></font></font><br>
If <font class="italic">arg</font> is <font class="italic">1</font>, trapping is enabled.  If it is <font class="italic">0</font>,
trapping is disabled.
</div>
.eof
</body>
</html>

